@0xbrainkid This looks pretty good, and elegant. Thank you. If you don't mind - what's the best way for me to use this to replicate your results? I can add a docs section on this, or perhaps you could create a quickstart with what external services I need? Docs are in Fumadocs format in this repo - if you add it to the docs, the MCP-Framework MCP server will be able to integrate it automatically https://github.com/QuantGeekDev/mcp-framework-docs

@QuantGeekDev — glad it fits well! Here's the quickstart:

Quickstart

1. No external services needed for basic usage. The provider queries the AgentFolio public API (api.agentfolio.bot), which is free and requires no API key.

2. Minimal test setup:

import { SATPProvider } from "mcp-framework";

// Allow all agents, just annotate requests with trust data
const provider = new SATPProvider({ onMissing: "allow" });

// Or enforce minimum trust score
const strictProvider = new SATPProvider({
  minTrustScore: 50,
  requireVerified: true,
  onMissing: "reject",
});

3. Testing with a real agent:

Send a request with the header x-agent-id: brainGrowth — that's a verified agent on AgentFolio with a trust score of 335. The provider will return the trust data in AuthResult.data.agentTrust.

4. Testing without an agent:

With onMissing: "allow" (default), requests without x-agent-id pass through normally with agentTrust: null. Existing servers aren't affected.

Docs

Happy to add a docs page in Fumadocs format. I'll push a follow-up commit to this PR with:

• docs/auth/satp.mdx — quickstart + configuration reference + examples
• Brief mention in the auth overview page

Give me a few hours and I'll have the docs commit ready.

that is quite neat. are there any rate limits that should be enforced for this on client code?

@QuantGeekDev — good question. The AgentFolio API has a generous free tier (no key needed) with soft rate limits:

• 100 requests/minute per IP (plenty for most servers)
• The built-in cache (cacheTtlMs: 300000 default = 5 min) means repeated requests for the same agent hit cache, not the API
• In practice: a server with 10 unique agents calling tools gets ~10 API calls every 5 minutes, well within limits

For high-throughput deployments, two options:

1. Increase cacheTtlMs (e.g., 900000 = 15 min cache) — trust scores change slowly, longer cache is fine
2. The provider handles API failures gracefully — if the API is unreachable or returns an error, it falls back to null (no trust data) rather than blocking the request

No client-side rate limiting needed in the provider code — the cache handles it naturally. Should I add a note about this in the docs?

This is great. Merging and will add to next release. Thank you for your contribution